<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Objects &mdash; The Logtalk Handbook v3.93.0-b01 documentation</title>
      <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d75fae25" />
      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=19f00094" />
      <link rel="stylesheet" type="text/css" href="../_static/css/custom.css?v=396eccfe" />

  
  <!--[if lt IE 9]>
    <script src="../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
        <script src="../_static/jquery.js?v=5d32c60e"></script>
        <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
        <script src="../_static/documentation_options.js?v=c8100655"></script>
        <script src="../_static/doctools.js?v=9a2dae69"></script>
        <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="../_static/js/theme.js"></script>
    <!-- begin favicon -->
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
    <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png" />
    <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png" />
    <link rel="manifest" href="/site.webmanifest" />
    <link rel="mask-icon" href="/safari-pinned-tab.svg" color="#5bbad5" />
    <meta name="msapplication-TileColor" content="#355b95" />
    <meta name="theme-color" content="#ffffff" />
    <!-- end favicon -->
    
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Protocols" href="protocols.html" />
    <link rel="prev" title="Messages" href="messages.html" />
   
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >

          
          
          <a href="../index.html" class="icon icon-home">
            The Logtalk Handbook
              <img src="../_static/logtalk.gif" class="logo" alt="Logo"/>
          </a>
              <div class="version">
                3.93.0
              </div>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
    
              <p class="caption" role="heading"><span class="caption-text">Contents</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="index.html">User Manual</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="declarative.html">Declarative object-oriented programming</a></li>
<li class="toctree-l2"><a class="reference internal" href="features.html">Main features</a></li>
<li class="toctree-l2"><a class="reference internal" href="nomenclature.html">Nomenclature</a></li>
<li class="toctree-l2"><a class="reference internal" href="messages.html">Messages</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Objects</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#objects-prototypes-classes-and-instances">Objects, prototypes, classes, and instances</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#prototypes">Prototypes</a></li>
<li class="toctree-l4"><a class="reference internal" href="#classes">Classes</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#defining-a-new-object">Defining a new object</a></li>
<li class="toctree-l3"><a class="reference internal" href="#parametric-objects">Parametric objects</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#accessing-object-parameters">Accessing object parameters</a></li>
<li class="toctree-l4"><a class="reference internal" href="#parametric-object-proxies">Parametric object proxies</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#finding-defined-objects">Finding defined objects</a></li>
<li class="toctree-l3"><a class="reference internal" href="#creating-a-new-object-at-runtime">Creating a new object at runtime</a></li>
<li class="toctree-l3"><a class="reference internal" href="#abolishing-an-existing-object">Abolishing an existing object</a></li>
<li class="toctree-l3"><a class="reference internal" href="#object-directives">Object directives</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#object-initialization">Object initialization</a></li>
<li class="toctree-l4"><a class="reference internal" href="#dynamic-objects">Dynamic objects</a></li>
<li class="toctree-l4"><a class="reference internal" href="#object-documentation">Object documentation</a></li>
<li class="toctree-l4"><a class="reference internal" href="#loading-files-into-an-object">Loading files into an object</a></li>
<li class="toctree-l4"><a class="reference internal" href="#declaring-object-aliases">Declaring object aliases</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#object-relationships">Object relationships</a></li>
<li class="toctree-l3"><a class="reference internal" href="#object-properties">Object properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="#built-in-objects">Built-in objects</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#the-built-in-pseudo-object-user">The built-in pseudo-object <code class="docutils literal notranslate"><span class="pre">user</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#the-built-in-object-logtalk">The built-in object <code class="docutils literal notranslate"><span class="pre">logtalk</span></code></a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#multi-threading-applications">Multi-threading applications</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="protocols.html">Protocols</a></li>
<li class="toctree-l2"><a class="reference internal" href="categories.html">Categories</a></li>
<li class="toctree-l2"><a class="reference internal" href="predicates.html">Predicates</a></li>
<li class="toctree-l2"><a class="reference internal" href="inheritance.html">Inheritance</a></li>
<li class="toctree-l2"><a class="reference internal" href="events.html">Event-driven programming</a></li>
<li class="toctree-l2"><a class="reference internal" href="threads.html">Multi-threading programming</a></li>
<li class="toctree-l2"><a class="reference internal" href="errors.html">Error handling</a></li>
<li class="toctree-l2"><a class="reference internal" href="reflection.html">Reflection</a></li>
<li class="toctree-l2"><a class="reference internal" href="programming.html">Writing and running applications</a></li>
<li class="toctree-l2"><a class="reference internal" href="printing.html">Printing messages and asking questions</a></li>
<li class="toctree-l2"><a class="reference internal" href="expansion.html">Term and goal expansion</a></li>
<li class="toctree-l2"><a class="reference internal" href="documenting.html">Documenting</a></li>
<li class="toctree-l2"><a class="reference internal" href="debugging.html">Debugging</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance.html">Performance</a></li>
<li class="toctree-l2"><a class="reference internal" href="installing.html">Installing Logtalk</a></li>
<li class="toctree-l2"><a class="reference internal" href="migration.html">Prolog integration and migration</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../refman/index.html">Reference Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="../faq/index.html">FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="../devtools/index.html">Developer Tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../libraries/index.html">Libraries</a></li>
<li class="toctree-l1"><a class="reference internal" href="../ports/index.html">Ports</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contributions/index.html">Contributions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
<li class="toctree-l1"><a class="reference internal" href="../bibliography.html">Bibliography</a></li>
<li class="toctree-l1"><a class="reference internal" href="../genindex.html">Index</a></li>
</ul>

    <p class="caption"><span class="caption-text">External Contents</span></p>
    <ul>
    <li class="toctree-l1"><a class="reference internal" href="../../apis/index.html">APIs</a></li>
    <li class="toctree-l1"><a class="reference internal" href="https://logtalk.org">Logtalk website</a></li>
    <li class="toctree-l1"><a class="reference internal" href="https://github.com/LogtalkDotOrg/logtalk3">GitHub repo</a></li>
    </ul>
  
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../index.html">The Logtalk Handbook</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
          <li class="breadcrumb-item"><a href="index.html">User Manual</a></li>
      <li class="breadcrumb-item active">Objects</li>
      <li class="wy-breadcrumbs-aside">
              <a href="https://github.com/LogtalkDotOrg/logtalk3/blob/master/docs/handbook/sources/userman/objects.rst" class="fa fa-github"> Edit on GitHub</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section id="objects">
<span id="objects-objects"></span><h1>Objects<a class="headerlink" href="#objects" title="Link to this heading"></a></h1>
<p>The main goal of Logtalk objects is the encapsulation and reuse of
predicates. Instead of a single database containing all your code,
Logtalk objects provide separated namespaces or databases, allowing the
partitioning of code into more manageable parts. Logtalk is a <em>declarative
programming language</em> and does not aim to bring some sort of new dynamic
state change concept to Logic Programming or Prolog.</p>
<p>Logtalk, defines two built-in objects, <a class="reference external" href="../../apis/user_0.html#user-0" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">user</span></a> and
<a class="reference external" href="../../apis/logtalk_0.html#logtalk-0" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">logtalk</span></a>, which are described at the end of this
section.</p>
<section id="objects-prototypes-classes-and-instances">
<span id="objects-roles"></span><h2>Objects, prototypes, classes, and instances<a class="headerlink" href="#objects-prototypes-classes-and-instances" title="Link to this heading"></a></h2>
<p>There are only three kinds of encapsulation entities in Logtalk:
<em>objects</em>, <em>protocols</em>, and <em>categories</em>. Logtalk uses the term <em>object</em>
in a broad sense. The terms <em>prototype</em>, <em>parent</em>, <em>class</em>, <em>subclass</em>,
<em>superclass</em>, <em>metaclass</em>, and <em>instance</em> always designate an object.
Different names are used to emphasize the <em>role</em> played by an object in
a particular context. I.e. we use a term other than object when we want
to make the relationship with other objects explicit. For example, an
object with an <em>instantiation</em> relation with another object plays the role
of an <em>instance</em>, while the instantiated object plays the role of a
<em>class</em>; an object with a <em>specialization</em> relation with another object
plays the role of a <em>subclass</em>, while the specialized object plays the
role of a <em>superclass</em>; an object with an <em>extension</em> relation with
another object plays the role of a <em>prototype</em>, the same for the extended
object. A <em>stand-alone</em> object, i.e. an object with no relations with
other objects, is always interpreted as a prototype. In Logtalk, entity
relations essentially define <em>patterns</em> of code reuse. An entity is
compiled according to the roles it plays.</p>
<p>Logtalk allows you to work from standalone objects to any kind of
hierarchy, either class-based or prototype-based. You may use single or
multiple inheritance, use or forgo metaclasses, implement reflective
designs, use parametric objects, and take advantage of protocols and
categories (think components).</p>
<section id="prototypes">
<span id="objects-prototypes"></span><h3>Prototypes<a class="headerlink" href="#prototypes" title="Link to this heading"></a></h3>
<p>Prototypes are either self-defined objects or objects defined as
extensions to other prototypes with whom they share common properties.
Prototypes are ideal for representing one-of-a-kind objects. Prototypes
usually represent concrete objects in the application domain. When
linking prototypes using <em>extension</em> relations, Logtalk uses the term
<em>prototype hierarchies</em> although most authors prefer to use the term
<em>hierarchy</em> only with class generalization/specialization relations. In
the context of logic programming, prototypes are often the ideal
replacement for modules.</p>
</section>
<section id="classes">
<span id="objects-classes"></span><h3>Classes<a class="headerlink" href="#classes" title="Link to this heading"></a></h3>
<p>Classes are used to represent abstractions of common properties of sets
of objects. Classes often provide an ideal structuring solution when you
want to express hierarchies of abstractions or work with many similar
objects. Classes are used indirectly through <em>instantiation</em>. Contrary
to most object-oriented programming languages, instances can be created
both dynamically at runtime or defined in a source file like other
objects. Using classes requires defining at least one <a class="reference internal" href="../glossary.html#term-metaclass"><span class="xref std std-term">metaclass</span></a>,
as explained below.</p>
</section>
</section>
<section id="defining-a-new-object">
<span id="objects-defining"></span><h2>Defining a new object<a class="headerlink" href="#defining-a-new-object" title="Link to this heading"></a></h2>
<p>We can define a new object in the same way we write Prolog code: by
using a text editor. Logtalk source files may contain one or more
objects, categories, or protocols. If you prefer to define each entity
in its own source file, it is recommended that the file be named after
the object. By default, all Logtalk source files use the extension
<code class="docutils literal notranslate"><span class="pre">.lgt</span></code> but this is optional and can be set in the adapter files.
Intermediate Prolog source files (generated by the Logtalk compiler)
have, by default, a <code class="docutils literal notranslate"><span class="pre">_lgt</span></code> suffix and a <code class="docutils literal notranslate"><span class="pre">.pl</span></code> extension. Again, this
can be set to match the needs of a particular Prolog compiler in the
corresponding adapter file. For instance, we may define an object named
<code class="docutils literal notranslate"><span class="pre">vehicle</span></code> and save it in a <code class="docutils literal notranslate"><span class="pre">vehicle.lgt</span></code> source file, which will be
compiled to a <code class="docutils literal notranslate"><span class="pre">vehicle_lgt.pl</span></code> Prolog file (depending on the
<a class="reference internal" href="../glossary.html#term-backend-Prolog-compiler"><span class="xref std std-term">backend compiler</span></a>, the names of the
intermediate Prolog files may include a directory hash and a process
identifier to prevent file name clashes when embedding Logtalk
applications or running parallel Logtalk processes).</p>
<p>Object names can be atoms or compound terms (when defining parametric
objects, see below). Objects, categories, and protocols share the same
name space: we cannot have an object with the same name as a protocol or
a category.</p>
<p>Object code (directives and predicates) is textually encapsulated by
using two Logtalk directives: <a class="reference internal" href="../refman/directives/object_1_5.html#directives-object-1-5"><span class="std std-ref">object/1-5</span></a> and
<a class="reference internal" href="../refman/directives/end_object_0.html#directives-end-object-0"><span class="std std-ref">end_object/0</span></a>. The simplest object will be one
that is self-contained, not depending on any other Logtalk entity:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(<span class="nv">Object</span>).
    ...
<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>If an object implements one or more protocols then the opening directive
will be:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(<span class="nv">Object</span>,
    <span class="k">implements</span>([<span class="nv">Protocol1</span>, <span class="nv">Protocol2</span>, ...])).
    ...
<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>An object can import one or more categories:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(<span class="nv">Object</span>,
    <span class="k">imports</span>([<span class="nv">Category1</span>, <span class="nv">Category2</span>, ...])).
    ...
<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>If an object both implements protocols and imports categories, then we
will write:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(<span class="nv">Object</span>,
    <span class="k">implements</span>([<span class="nv">Protocol1</span>, <span class="nv">Protocol2</span>, ...]),
    <span class="k">imports</span>([<span class="nv">Category1</span>, <span class="nv">Category2</span>, ...])).
    ...
<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>In object-oriented programming, objects are usually organized in
hierarchies that enable interface and code sharing by inheritance. In
Logtalk, we can construct prototype-based hierarchies by writing:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(<span class="nv">Prototype</span>,
    <span class="k">extends</span>(<span class="nv">Parent</span>)).
    ...
<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>We can also have class-based hierarchies by defining instantiation and
specialization relations between objects. To define an object as a class
instance we will write:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(<span class="nv">Object</span>,
    <span class="k">instantiates</span>(<span class="nv">Class</span>)).
    ...
<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>A class may specialize another class, its superclass:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(<span class="nv">Class</span>,
    <span class="k">specializes</span>(<span class="nv">Superclass</span>)).
    ...
<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>If we are defining a reflexive system where every class is also an
instance, we will probably be using the following pattern:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(<span class="nv">Class</span>,
    <span class="k">instantiates</span>(<span class="nv">Metaclass</span>),
    <span class="k">specializes</span>(<span class="nv">Superclass</span>)).
    ...
<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>In short, an object can be a <em>stand-alone</em> object or be part of an
object hierarchy. The hierarchy can be prototype-based (defined by
extending other objects) or class-based (with instantiation and
specialization relations). An object may also implement one or more
protocols or import one or more categories.</p>
<p>A <em>stand-alone</em> object (i.e., an object with no extension, instantiation,
or specialization relations with other objects) always plays the role of
a prototype, that is, a self-describing object. If we want to use classes
and instances, then we will need to specify at least one instantiation
or specialization relation. The best way to do this is to define a set
of objects that provide the basis of a reflective system <a class="reference internal" href="../bibliography.html#cointe87" id="id1"><span>[Cointe87]</span></a>,
<a class="reference internal" href="../bibliography.html#moura94" id="id2"><span>[Moura94]</span></a>. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="c">% avoid the inevitable unknown entity warnings as in a</span>
<span class="c">% reflective system there will always be references to</span>
<span class="c">% an entity that will be defined after the reference</span>

<span class="p">:- </span><span class="k">set_logtalk_flag</span>(unknown_entities, silent).


<span class="c">% default root of the inheritance graph</span>
<span class="c">% providing predicates common to all objects</span>

<span class="p">:- </span><span class="k">object</span>(object,
    <span class="k">instantiates</span>(class)).
    ...
<span class="p">:- </span><span class="k">end_object</span>.


<span class="c">% default metaclass for all classes providing</span>
<span class="c">% predicates common to all instantiable classes</span>

<span class="p">:- </span><span class="k">object</span>(class,
    <span class="k">instantiates</span>(class),
    <span class="k">specializes</span>(abstract_class)).
    ...
<span class="p">:- </span><span class="k">end_object</span>.


<span class="c">% default metaclass for all abstract classes</span>
<span class="c">% providing predicates common to all classes</span>

<span class="p">:- </span><span class="k">object</span>(abstract_class,
    <span class="k">instantiates</span>(class),
    <span class="k">specializes</span>(object)).
    ...
<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>Note that with these instantiation and specialization relations,
<code class="docutils literal notranslate"><span class="pre">object</span></code>, <code class="docutils literal notranslate"><span class="pre">class</span></code>, and <code class="docutils literal notranslate"><span class="pre">abstract_class</span></code> are, at the same time,
classes and instances of some class. In addition, each object inherits
its own predicates and the predicates of the other two objects without
any inheritance loop.</p>
<p>When a full-blown reflective system solution is not needed, the above
scheme can be simplified by making an object an instance of itself, i.e.
by making a class its own metaclass. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(class,
    <span class="k">instantiates</span>(class)).
    ...
<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>We can use, in the same application, both prototype and class-based
hierarchies (and freely exchange messages between all objects). We
cannot, however, mix the two types of hierarchies by, e.g., specializing
an object that extends another object in this current Logtalk version.</p>
<p>Logtalk also supports public, protected, and private inheritance. See
the <a class="reference internal" href="inheritance.html#inheritance-scope"><span class="std std-ref">inheritance</span></a> section for details.</p>
</section>
<section id="parametric-objects">
<span id="objects-parametric"></span><h2>Parametric objects<a class="headerlink" href="#parametric-objects" title="Link to this heading"></a></h2>
<p>Parametric objects have a compound term as identifier where all the
arguments of the compound term are variables. These variables can be
bound when sending a message or become bound when a message to the object
succeeds, thus acting as <em>object parameters</em>. The object predicates
can be coded to depend on those parameters, which are logical variables
shared by all object predicates. When an object state is set at object
creation and never changed, parameters provide a better solution than
using the object’s database via asserts. Parametric objects can also be
used to associate a set of predicates to terms that share a common
functor and arity.</p>
<section id="accessing-object-parameters">
<h3>Accessing object parameters<a class="headerlink" href="#accessing-object-parameters" title="Link to this heading"></a></h3>
<p>Object parameters can be accessed using <a class="reference internal" href="../glossary.html#term-parameter-variable"><span class="xref std std-term">parameter variables</span></a>
or built-in execution context methods. Parameter variables is the
recommended solution to access object parameters. Although they
introduce a concept of entity global variables, their unique syntax
(<code class="docutils literal notranslate"><span class="pre">_ParameterName_</span></code>) avoids conflicts, makes them easily recognizable,
and distinguishes them from other named anonymous variables. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(foo(<span class="nv">_Bar_</span>, <span class="nv">_Baz_</span>, ...)).

    ...
    bar(<span class="nv">_Bar_</span>).

    baz <span class="o">:-</span>
        baz(<span class="nv">_Baz_</span>),
        ... .
</pre></div>
</div>
<p>Note that using parameter variables doesn’t change the fact that entity
parameters are logical variables. Parameter variables simplify code
maintenance by allowing parameters to be added, reordered, or removed
without having to specify or update parameter indexes.</p>
<p>Logtalk provides also a <a class="reference internal" href="../refman/methods/parameter_2.html#methods-parameter-2"><span class="std std-ref">parameter/2</span></a> built-in local method
to access individual parameters:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(foo(<span class="nv">_Bar</span>, <span class="nv">_Baz</span>, ...)).

    ...
    bar(<span class="nv">Bar</span>) <span class="o">:-</span>
        <span class="k">parameter</span>(<span class="m">1</span>, <span class="nv">Bar</span>).

    baz <span class="o">:-</span>
        <span class="k">parameter</span>(<span class="m">2</span>, <span class="nv">Baz</span>),
        baz(<span class="nv">Baz</span>),
        ... .
</pre></div>
</div>
<p>An alternative solution is to use the built-in local method
<a class="reference internal" href="../refman/methods/this_1.html#methods-this-1"><span class="std std-ref">this/1</span></a>, which allows access to all parameters with a single
call. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(foo(<span class="nv">_Bar</span>, <span class="nv">_Baz</span>, ...)).

    ...
    baz <span class="o">:-</span>
        <span class="k">this</span>(foo(<span class="nv">_</span>, <span class="nv">Baz</span>, ...)),
        baz(<span class="nv">Baz</span>),
        ... .
</pre></div>
</div>
<p>Both solutions are equally efficient as calls to the methods <code class="docutils literal notranslate"><span class="pre">this/1</span></code>
and <code class="docutils literal notranslate"><span class="pre">parameter/2</span></code> are usually compiled inline into a clause head
unification. The drawback of this second solution is that we must check
all calls of <code class="docutils literal notranslate"><span class="pre">this/1</span></code> if we change the object name. Note that we can’t
use these method with the message-sending operators
(<a class="reference internal" href="../refman/control/send_to_object_2.html#control-send-to-object-2"><span class="std std-ref">(::)/2</span></a>, <a class="reference internal" href="../refman/control/send_to_self_1.html#control-send-to-self-1"><span class="std std-ref">(::)/1</span></a>, or
<a class="reference internal" href="../refman/control/call_super_1.html#control-call-super-1"><span class="std std-ref">(^^)/1</span></a>).</p>
<p>When storing a parametric object in its own source file, the convention
is to name the file after the object, with the object arity appended.
For instance, when defining an object named <code class="docutils literal notranslate"><span class="pre">sort(Type)</span></code>, we may save
it in a <code class="docutils literal notranslate"><span class="pre">sort_1.lgt</span></code> text file. This way it is easy to avoid file name
clashes when saving Logtalk entities that have the same functor but
different arity.</p>
</section>
<section id="parametric-object-proxies">
<h3>Parametric object proxies<a class="headerlink" href="#parametric-object-proxies" title="Link to this heading"></a></h3>
<p>Compound terms with the same functor and with the same number of
arguments as a parametric object identifier may act as <em>proxies</em> to a
parametric object. Proxies may be stored on the database as Prolog facts
and be used to represent different instantiations of a parametric object
identifier. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(circle(<span class="nv">_Id_</span>, <span class="nv">_Radius_</span>, <span class="nv">_Color_</span>)).

<span class="p">    :- </span><span class="k">public</span>(area<span class="o">/</span><span class="m">1</span>).
    ...

<span class="p">:- </span><span class="k">end_object</span>.

<span class="c">% parametric object proxies:</span>
circle(<span class="s">&#39;#1&#39;</span>, <span class="m">1.23</span>, blue).
circle(<span class="s">&#39;#2&#39;</span>, <span class="m">3.71</span>, yellow).
circle(<span class="s">&#39;#3&#39;</span>, <span class="m">0.39</span>, green).
circle(<span class="s">&#39;#4&#39;</span>, <span class="m">5.74</span>, black).
circle(<span class="s">&#39;#5&#39;</span>, <span class="m">8.32</span>, cyan).
</pre></div>
</div>
<p>Logtalk provides a convenient notation for accessing proxies
represented as Prolog facts when sending a message:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>..., <span class="k">{</span><span class="nv">Proxy</span><span class="k">}</span><span class="o">::</span><span class="nv">Message</span>, ...
</pre></div>
</div>
<p>For example, using the <code class="docutils literal notranslate"><span class="pre">circle/3</span></code> parametric object above, we can
compute a list with the areas of all circles using the following goal:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>| <span class="o">?-</span> <span class="k">findall</span>(<span class="nv">Area</span>, <span class="k">{</span>circle(<span class="nv">_</span>, <span class="nv">_</span>, <span class="nv">_</span>)<span class="k">}</span><span class="o">::</span>area(<span class="nv">Area</span>), <span class="nv">Areas</span>).

<span class="nv">Areas</span> <span class="o">=</span> [<span class="m">4.75291</span>, <span class="m">43.2412</span>, <span class="m">0.477836</span>, <span class="m">103.508</span>, <span class="m">217.468</span>].
</pre></div>
</div>
<p>In this context, the proxy argument is proved as a plain Prolog goal. If
successful, the message is sent to the corresponding parametric object.
Typically, the proof allows retrieval of parameter instantiations. This
construct can either be used with a proxy argument that is sufficiently
instantiated in order to unify with a single Prolog fact or with a proxy
argument that unifies with several facts on backtracking.</p>
</section>
</section>
<section id="finding-defined-objects">
<span id="objects-finding"></span><h2>Finding defined objects<a class="headerlink" href="#finding-defined-objects" title="Link to this heading"></a></h2>
<p>We can find, by backtracking, all defined objects by calling the
<a class="reference internal" href="../refman/predicates/current_object_1.html#predicates-current-object-1"><span class="std std-ref">current_object/1</span></a> built-in predicate with an
unbound argument:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- current_object(Object).
Object = logtalk ;
Object = user ;
...
</pre></div>
</div>
<p>This predicate can also be used to test if an object is defined by
calling it with a valid object identifier (an atom or a compound term).</p>
</section>
<section id="creating-a-new-object-at-runtime">
<span id="objects-creating"></span><h2>Creating a new object at runtime<a class="headerlink" href="#creating-a-new-object-at-runtime" title="Link to this heading"></a></h2>
<p>An object can be dynamically created at runtime by using the
<a class="reference internal" href="../refman/predicates/create_object_4.html#predicates-create-object-4"><span class="std std-ref">create_object/4</span></a> built-in predicate:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- create_object(Object, Relations, Directives, Clauses).
</pre></div>
</div>
<p>The first argument should be either a variable or the name of the new
object (a Prolog atom or compound term, which must not match any
existing entity name). The remaining three arguments correspond to the
relations described in the opening object directive and to the object
code contents (directives and clauses).</p>
<p>For example, the call:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- create_object(
         foo,
         [extends(bar)],
         [public(foo/1)],
         [foo(1), foo(2)]
     ).
</pre></div>
</div>
<p>is equivalent to compiling and loading the object:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(foo,
    <span class="k">extends</span>(bar)).

<span class="p">    :- </span><span class="k">dynamic</span>.

<span class="p">    :- </span><span class="k">public</span>(foo<span class="o">/</span><span class="m">1</span>).
    foo(<span class="m">1</span>).
    foo(<span class="m">2</span>).

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>If we need to create a lot of (dynamic) objects at runtime, then it is best
to define a metaclass or a prototype with a predicate that will call this
built-in predicate to make new objects. This predicate may provide automatic
object name generation, name checking, and accept object initialization
options.</p>
</section>
<section id="abolishing-an-existing-object">
<span id="objects-abolishing"></span><h2>Abolishing an existing object<a class="headerlink" href="#abolishing-an-existing-object" title="Link to this heading"></a></h2>
<p>Dynamic objects can be abolished using the <a class="reference internal" href="../refman/predicates/abolish_object_1.html#predicates-abolish-object-1"><span class="std std-ref">abolish_object/1</span></a>
built-in predicate:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- abolish_object(Object).
</pre></div>
</div>
<p>The argument must be an identifier of a defined dynamic object;
otherwise an error will be thrown.</p>
</section>
<section id="object-directives">
<span id="objects-directives"></span><h2>Object directives<a class="headerlink" href="#object-directives" title="Link to this heading"></a></h2>
<p>Object directives are used to set initialization goals, define object
properties, document an object dependencies on other Logtalk
entities, and load the contents of files into an object.</p>
<section id="object-initialization">
<span id="objects-initialization"></span><h3>Object initialization<a class="headerlink" href="#object-initialization" title="Link to this heading"></a></h3>
<p>We can define a goal to be executed as soon as an object is (compiled
and) loaded to memory with the <a class="reference internal" href="../refman/directives/initialization_1.html#directives-initialization-1"><span class="std std-ref">initialization/1</span></a>
directive:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">initialization</span>(<span class="nv">Goal</span>).
</pre></div>
</div>
<p>The argument can be any valid Logtalk goal. For example, a call to a
local predicate:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(foo).

<span class="p">    :- </span><span class="k">initialization</span>(init).
<span class="p">    :- </span><span class="k">private</span>(init<span class="o">/</span><span class="m">0</span>).

    init <span class="o">:-</span>
        ... .

    ...

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>Or a message to another object:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(assembler).

<span class="p">    :- </span><span class="k">initialization</span>(control<span class="o">::</span>start).
    ...

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>Another common initialization goal is a message to <em>self</em> in order to call
an inherited or imported predicate. For example, assuming that we have a
<code class="docutils literal notranslate"><span class="pre">monitor</span></code> category defining a <code class="docutils literal notranslate"><span class="pre">reset/0</span></code> predicate, we could write:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(profiler,
    <span class="k">imports</span>(monitor)).

<span class="p">    :- </span><span class="k">initialization</span>(<span class="o">::</span>reset).
    ...

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>Note, however, that descendant objects do not inherit initialization
directives. In this context, <em>self</em> denotes the object that contains the
directive. Also note that object initialization does not necessarily mean
setting an object dynamic state.</p>
</section>
<section id="dynamic-objects">
<span id="objects-dynamic"></span><h3>Dynamic objects<a class="headerlink" href="#dynamic-objects" title="Link to this heading"></a></h3>
<p>Similar to Prolog predicates, an object can be either static or dynamic.
An object created during the execution of a program is always dynamic.
An object defined in a file can be either dynamic or static. Dynamic
objects are declared by using the <a class="reference internal" href="../refman/directives/dynamic_0.html#directives-dynamic-0"><span class="std std-ref">dynamic/0</span></a> directive in the
object source code:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">dynamic</span>.
</pre></div>
</div>
<p>The directive must precede any predicate directives or clauses. Please
be aware that using dynamic code results in a performance hit when
compared to static code. We should only use dynamic objects when these
need to be abolished during program execution. In addition, note that we
can declare and define dynamic predicates within a static object.</p>
</section>
<section id="object-documentation">
<span id="objects-documentation"></span><h3>Object documentation<a class="headerlink" href="#object-documentation" title="Link to this heading"></a></h3>
<p>An object can be documented with arbitrary user-defined information
by using the <a class="reference internal" href="../refman/directives/info_1.html#directives-info-1"><span class="std std-ref">info/1</span></a> entity directive. See the
<a class="reference internal" href="documenting.html#documenting-documenting"><span class="std std-ref">Documenting</span></a> section for details.</p>
</section>
<section id="loading-files-into-an-object">
<span id="objects-include"></span><h3>Loading files into an object<a class="headerlink" href="#loading-files-into-an-object" title="Link to this heading"></a></h3>
<p>The <a class="reference internal" href="../refman/directives/include_1.html#directives-include-1"><span class="std std-ref">include/1</span></a> directive
can be used to load the contents of a file into an object. A typical usage
scenario is to load a plain Prolog file into an object, thus providing a
simple way to encapsulate its contents. For example, assume a <code class="docutils literal notranslate"><span class="pre">cities.pl</span></code>
file defining facts for a <code class="docutils literal notranslate"><span class="pre">city/4</span></code> predicate. We could define a wrapper
for this database by writing:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(cities).

<span class="p">    :- </span><span class="k">public</span>(city<span class="o">/</span><span class="m">4</span>).

<span class="p">    :- </span><span class="k">include</span>(dbs(<span class="s">&#39;cities.pl&#39;</span>)).

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">include/1</span></code> directive can also be used when creating an object
dynamically. For example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- create_object(cities, [], [public(city/4), include(dbs(&#39;cities.pl&#39;))], []).
</pre></div>
</div>
</section>
<section id="declaring-object-aliases">
<span id="objects-object-aliases"></span><h3>Declaring object aliases<a class="headerlink" href="#declaring-object-aliases" title="Link to this heading"></a></h3>
<p>The <a class="reference internal" href="../refman/directives/uses_1.html#directives-uses-1"><span class="std std-ref">uses/1</span></a> directive can be used to declare object aliases.
The typical uses of this directive include shortening long object names,
working consistently with specific parameterizations of parametric objects,
and simplifying experimenting with different object implementations of the
same protocol when using explicit message-sending.</p>
</section>
</section>
<section id="object-relationships">
<span id="objects-relationships"></span><h2>Object relationships<a class="headerlink" href="#object-relationships" title="Link to this heading"></a></h2>
<p>Logtalk provides six sets of built-in predicates that enable us to query
the system about the relationships that an object has with other entities.</p>
<p>The <a class="reference internal" href="../refman/predicates/instantiates_class_2_3.html#predicates-instantiates-class-2-3"><span class="std std-ref">instantiates_class/2-3</span></a> built-in predicates can be
used to query all instantiation relations:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- instantiates_class(Instance, Class).
</pre></div>
</div>
<p>or, if we also want to know the instantiation scope:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- instantiates_class(Instance, Class, Scope).
</pre></div>
</div>
<p>Specialization relations can be found by using the
<a class="reference internal" href="../refman/predicates/specializes_class_2_3.html#predicates-specializes-class-2-3"><span class="std std-ref">specializes_class/2-3</span></a> built-in predicates:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- specializes_class(Class, Superclass).
</pre></div>
</div>
<p>or, if we also want to know the specialization scope:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- specializes_class(Class, Superclass, Scope).
</pre></div>
</div>
<p>For prototypes, we can query extension relations using the
<a class="reference internal" href="../refman/predicates/extends_object_2_3.html#predicates-extends-object-2-3"><span class="std std-ref">extends_object/2-3</span></a> built-in predicates:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- extends_object(Object, Parent).
</pre></div>
</div>
<p>or, if we also want to know the extension scope:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- extends_object(Object, Parent, Scope).
</pre></div>
</div>
<p>In order to find which objects import which categories, we can use the
<a class="reference internal" href="../refman/predicates/imports_category_2_3.html#predicates-imports-category-2-3"><span class="std std-ref">imports_category/2-3</span></a> built-in predicates:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- imports_category(Object, Category).
</pre></div>
</div>
<p>or, if we also want to know the importation scope:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- imports_category(Object, Category, Scope).
</pre></div>
</div>
<p>To find which objects implements which protocols, we can use the
<a class="reference internal" href="../refman/predicates/implements_protocol_2_3.html#predicates-implements-protocol-2-3"><span class="std std-ref">implements_protocol/2-3</span></a> and
<a class="reference internal" href="../refman/predicates/conforms_to_protocol_2_3.html#predicates-conforms-to-protocol-2-3"><span class="std std-ref">conforms_to_protocol/2-3</span></a> built-in predicates:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- implements_protocol(Object, Protocol, Scope).
</pre></div>
</div>
<p>or, if we also want to consider inherited protocols:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- conforms_to_protocol(Object, Protocol, Scope).
</pre></div>
</div>
<p>Note that, if we use an unbound first argument, we will need to use the
<a class="reference internal" href="../refman/predicates/current_object_1.html#predicates-current-object-1"><span class="std std-ref">current_object/1</span></a> built-in predicate to ensure that the
entity returned is an object and not a category.</p>
<p>To find which objects are explicitly complemented by categories, we can
use the <a class="reference internal" href="../refman/predicates/complements_object_2.html#predicates-complements-object-2"><span class="std std-ref">complements_object/2</span></a> built-in predicate:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- complements_object(Category, Object).
</pre></div>
</div>
<p>Note that more than one category may explicitly complement a single
object, and a single category can complement several objects.</p>
</section>
<section id="object-properties">
<span id="objects-properties"></span><h2>Object properties<a class="headerlink" href="#object-properties" title="Link to this heading"></a></h2>
<p>We can find the properties of defined objects by calling the built-in
predicate <a class="reference internal" href="../refman/predicates/object_property_2.html#predicates-object-property-2"><span class="std std-ref">object_property/2</span></a>:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- object_property(Object, Property).
</pre></div>
</div>
<p>The following object properties are supported:</p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">static</span></code></dt><dd><p>The object is static</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">dynamic</span></code></dt><dd><p>The object is dynamic (and thus can be abolished in runtime by
calling the <a class="reference internal" href="../refman/predicates/abolish_object_1.html#predicates-abolish-object-1"><span class="std std-ref">abolish_object/1</span></a> built-in predicate)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">built_in</span></code></dt><dd><p>The object is a built-in object (and thus always available)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">threaded</span></code></dt><dd><p>The object supports/makes multi-threading calls</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">file(Path)</span></code></dt><dd><p>Absolute path of the source file defining the object (if applicable)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">file(Basename,</span> <span class="pre">Directory)</span></code></dt><dd><p>Basename and directory of the source file defining the object (if
applicable); <code class="docutils literal notranslate"><span class="pre">Directory</span></code> always ends with a <code class="docutils literal notranslate"><span class="pre">/</span></code></p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">lines(BeginLine,</span> <span class="pre">EndLine)</span></code></dt><dd><p>Source file begin and end lines of the object definition (if
applicable)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">directive(BeginLine,</span> <span class="pre">EndLine)</span></code></dt><dd><p>Source file begin and end lines of the object opening directive (if
applicable)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">context_switching_calls</span></code></dt><dd><p>The object supports context-switching calls (i.e., can be used with
the <a class="reference internal" href="../refman/control/context_switch_2.html#control-context-switch-2"><span class="std std-ref">(&lt;&lt;)/2</span></a> debugging control construct)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">dynamic_declarations</span></code></dt><dd><p>The object supports dynamic declarations of predicates</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">events</span></code></dt><dd><p>Messages sent from the object generate events</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">source_data</span></code></dt><dd><p>Source data available for the object</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">complements(Permission)</span></code></dt><dd><p>The object supports complementing categories with the specified
permission (<code class="docutils literal notranslate"><span class="pre">allow</span></code> or <code class="docutils literal notranslate"><span class="pre">restrict</span></code>)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">complements</span></code></dt><dd><p>The object supports complementing categories</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">public(Resources)</span></code></dt><dd><p>List of public predicates and operators declared by the object</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">protected(Resources)</span></code></dt><dd><p>List of protected predicates and operators declared by the object</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">private(Resources)</span></code></dt><dd><p>List of private predicates and operators declared by the object</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">declares(Predicate,</span> <span class="pre">Properties)</span></code></dt><dd><p>List of <a class="reference internal" href="../refman/grammar.html#grammar-entity-properties"><span class="std std-ref">properties</span></a> for a predicate declared by the object</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">defines(Predicate,</span> <span class="pre">Properties)</span></code></dt><dd><p>List of <a class="reference internal" href="../refman/grammar.html#grammar-entity-properties"><span class="std std-ref">properties</span></a> for a predicate defined by the object</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">includes(Predicate,</span> <span class="pre">Entity,</span> <span class="pre">Properties)</span></code></dt><dd><p>List of <a class="reference internal" href="../refman/grammar.html#grammar-entity-properties"><span class="std std-ref">properties</span></a> for an object multifile predicate that are defined
in the specified entity (the properties include <code class="docutils literal notranslate"><span class="pre">number_of_clauses(Number)</span></code>, <code class="docutils literal notranslate"><span class="pre">number_of_rules(Number)</span></code>,
<code class="docutils literal notranslate"><span class="pre">lines(Start,End)</span></code>, and <code class="docutils literal notranslate"><span class="pre">line_count(Start)</span></code> with <code class="docutils literal notranslate"><span class="pre">Start</span></code> being the begin line of the
first multifile predicate clause)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">provides(Predicate,</span> <span class="pre">Entity,</span> <span class="pre">Properties)</span></code></dt><dd><p>List of <a class="reference internal" href="../refman/grammar.html#grammar-entity-properties"><span class="std std-ref">properties</span></a> for other entity multifile predicates that are
defined in the object (the properties include <code class="docutils literal notranslate"><span class="pre">number_of_clauses(Number)</span></code>, <code class="docutils literal notranslate"><span class="pre">number_of_rules(Number)</span></code>, and
<code class="docutils literal notranslate"><span class="pre">lines(Start,End)</span></code>, and <code class="docutils literal notranslate"><span class="pre">line_count(Start)</span></code> with <code class="docutils literal notranslate"><span class="pre">Start</span></code> being the begin line of the
first multifile predicate clause)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">alias(Entity,</span> <span class="pre">Properties)</span></code></dt><dd><p>List of <a class="reference internal" href="../refman/grammar.html#grammar-entity-properties"><span class="std std-ref">properties</span></a> for an <a class="reference internal" href="../glossary.html#term-entity-alias"><span class="xref std std-term">entity alias</span></a> declared by the object
(the properties include <code class="docutils literal notranslate"><span class="pre">object</span></code> in case of an object alias, <code class="docutils literal notranslate"><span class="pre">module</span></code> in case of a module alias,
<code class="docutils literal notranslate"><span class="pre">for(Original)</span></code>, <code class="docutils literal notranslate"><span class="pre">lines(Start,End)</span></code>, and <code class="docutils literal notranslate"><span class="pre">line_count(Start)</span></code> with <code class="docutils literal notranslate"><span class="pre">Start</span></code> being the begin line of the <code class="docutils literal notranslate"><span class="pre">uses/1</span></code> or
<code class="docutils literal notranslate"><span class="pre">use_module/1</span></code> directive)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">alias(Predicate,</span> <span class="pre">Properties)</span></code></dt><dd><p>List of <a class="reference internal" href="../refman/grammar.html#grammar-entity-properties"><span class="std std-ref">properties</span></a> for a <a class="reference internal" href="../glossary.html#term-predicate-alias"><span class="xref std std-term">predicate alias</span></a> declared by the object
(the properties include <code class="docutils literal notranslate"><span class="pre">predicate</span></code>, <code class="docutils literal notranslate"><span class="pre">for(Original)</span></code>, <code class="docutils literal notranslate"><span class="pre">from(Entity)</span></code>, <code class="docutils literal notranslate"><span class="pre">non_terminal(NonTerminal)</span></code>,
<code class="docutils literal notranslate"><span class="pre">lines(Start,End)</span></code>, and <code class="docutils literal notranslate"><span class="pre">line_count(Start)</span></code> with <code class="docutils literal notranslate"><span class="pre">Start</span></code> being the begin line of the alias directive)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">calls(Call,</span> <span class="pre">Properties)</span></code></dt><dd><p>List of <a class="reference internal" href="../refman/grammar.html#grammar-entity-properties"><span class="std std-ref">properties</span></a> for predicate calls made by the object (<code class="docutils literal notranslate"><span class="pre">Call</span></code>
is either a predicate indicator or a control construct such as
<code class="docutils literal notranslate"><span class="pre">(::)/1-2</span></code> or <code class="docutils literal notranslate"><span class="pre">(^^)/1</span></code> with a predicate indicator as argument; note
that <code class="docutils literal notranslate"><span class="pre">Call</span></code> may not be ground in case of a call to a control
construct where its argument is only known at runtime; the properties
include <code class="docutils literal notranslate"><span class="pre">caller(Caller)</span></code>, <code class="docutils literal notranslate"><span class="pre">alias(Alias)</span></code>, <code class="docutils literal notranslate"><span class="pre">non_terminal(NonTerminal)</span></code>,
<code class="docutils literal notranslate"><span class="pre">lines(Start,End)</span></code>, <code class="docutils literal notranslate"><span class="pre">line_count(Start)</span></code> with <code class="docutils literal notranslate"><span class="pre">Caller</span></code>, <code class="docutils literal notranslate"><span class="pre">Alias</span></code>, and <code class="docutils literal notranslate"><span class="pre">NonTerminal</span></code>
being predicate indicators and <code class="docutils literal notranslate"><span class="pre">Start</span></code> being the begin line of the
predicate clause or directive making the call)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">updates(Predicate,</span> <span class="pre">Properties)</span></code></dt><dd><p>List of <a class="reference internal" href="../refman/grammar.html#grammar-entity-properties"><span class="std std-ref">properties</span></a> for dynamic predicate updates (and also access
using the <code class="docutils literal notranslate"><span class="pre">clause/2</span></code> predicate) made by the object (<code class="docutils literal notranslate"><span class="pre">Predicate</span></code>
is either a predicate indicator or a control construct such as
<code class="docutils literal notranslate"><span class="pre">(::)/1-2</span></code> or <code class="docutils literal notranslate"><span class="pre">(:)/2</span></code> with a predicate indicator as argument; note
that <code class="docutils literal notranslate"><span class="pre">Predicate</span></code> may not be ground in case of a control construct
argument only known at runtime; the properties include
<code class="docutils literal notranslate"><span class="pre">updater(Updater)</span></code>, <code class="docutils literal notranslate"><span class="pre">alias(Alias)</span></code>, <code class="docutils literal notranslate"><span class="pre">non_terminal(NonTerminal)</span></code>,
<code class="docutils literal notranslate"><span class="pre">lines(Start,End)</span></code>, and <code class="docutils literal notranslate"><span class="pre">line_count(Start)</span></code> with <code class="docutils literal notranslate"><span class="pre">Updater</span></code> being a (possibly multifile)
predicate indicator, <code class="docutils literal notranslate"><span class="pre">Alias</span></code> and <code class="docutils literal notranslate"><span class="pre">NonTerminal</span></code> being predicate
indicators, and <code class="docutils literal notranslate"><span class="pre">Start</span></code> being the begin line of the predicate clause
or directive updating the predicate)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">number_of_clauses(Number)</span></code></dt><dd><p>Total number of predicate clauses defined in the object at compilation
time (includes both user-defined clauses and auxiliary clauses generated
by the compiler or by the <a class="reference internal" href="expansion.html#expansion-expansion"><span class="std std-ref">expansion hooks</span></a>
but does not include clauses for multifile predicates defined for other
entities or clauses for the object own multifile predicates contributed
by other entities)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">number_of_rules(Number)</span></code></dt><dd><p>Total number of predicate rules defined in the object at compilation
time (includes both user-defined rules and auxiliary rules generated
by the compiler or by the <a class="reference internal" href="expansion.html#expansion-expansion"><span class="std std-ref">expansion hooks</span></a>
but does not include rules for multifile predicates defined for other
entities or rules for the object own multifile predicates contributed
by other entities)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">number_of_user_clauses(Number)</span></code></dt><dd><p>Total number of user-defined predicate clauses defined in the object
at compilation time (does not include clauses for multifile predicates
defined for other entities or clauses for the object own multifile
predicates contributed by other entities)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">number_of_user_rules(Number)</span></code></dt><dd><p>Total number of user-defined predicate rules defined in the object at
compilation time (does not include rules for multifile predicates defined
for other entities or rules for the object own multifile predicates
contributed by other entities)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">debugging</span></code></dt><dd><p>The object is compiled in debug mode</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">module</span></code></dt><dd><p>The object resulted from the compilation of a Prolog module</p>
</dd>
</dl>
<p>When a predicate is called from an <code class="docutils literal notranslate"><span class="pre">initialization/1</span></code> directive, the
argument of the <code class="docutils literal notranslate"><span class="pre">caller/1</span></code> property is <code class="docutils literal notranslate"><span class="pre">(:-)/1</span></code>.</p>
<p>Some properties such as line numbers are only available when the object is
defined in a source file compiled with the <a class="reference internal" href="programming.html#flag-source-data"><span class="std std-ref">source_data</span></a>
flag turned on. Moreover, line numbers are only supported in
<a class="reference internal" href="../glossary.html#term-backend-Prolog-compiler"><span class="xref std std-term">backend Prolog compilers</span></a>
that provide access to the start line of a read term. When such support is
not available, the value <code class="docutils literal notranslate"><span class="pre">-1</span></code> is returned for the start and end lines.</p>
<p>The properties that return the number of clauses (rules) report the
clauses (rules) <em>textually defined in the object</em> for both multifile and
non-multifile predicates. Thus, these numbers exclude clauses (rules)
for multifile predicates <em>contributed</em> by other entities.</p>
</section>
<section id="built-in-objects">
<span id="objects-built-in"></span><h2>Built-in objects<a class="headerlink" href="#built-in-objects" title="Link to this heading"></a></h2>
<p>Logtalk defines some built-in objects that are always available for any
application.</p>
<section id="the-built-in-pseudo-object-user">
<span id="objects-user"></span><h3>The built-in pseudo-object <code class="docutils literal notranslate"><span class="pre">user</span></code><a class="headerlink" href="#the-built-in-pseudo-object-user" title="Link to this heading"></a></h3>
<p>The built-in <a class="reference external" href="../../apis/user_0.html#user-0" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">user</span></a> pseudo-object virtually contains all
user predicate definitions not encapsulated in a Logtalk entity (or a Prolog
module for backends supporting a module system). These predicates are
assumed to be implicitly declared public. Messages sent from this
pseudo-object, which includes messages sent from the top-level interpreter,
generate events when the default value of the <a class="reference internal" href="programming.html#flag-events"><span class="std std-ref">events</span></a>
flag is set to <code class="docutils literal notranslate"><span class="pre">allow</span></code>. Defining complementing categories for this
pseudo-object is not supported.</p>
<p>With some of the <a class="reference internal" href="../glossary.html#term-backend-Prolog-compiler"><span class="xref std std-term">backend Prolog compilers</span></a>
that support a module system, it is possible to load (the) Logtalk
(compiler/runtime) into a module other than the pseudo-module <code class="docutils literal notranslate"><span class="pre">user</span></code>. In
this case, the Logtalk pseudo-object <code class="docutils literal notranslate"><span class="pre">user</span></code> virtually contains all user
predicate definitions defined in the module where Logtalk was loaded.</p>
</section>
<section id="the-built-in-object-logtalk">
<span id="objects-logtalk"></span><h3>The built-in object <code class="docutils literal notranslate"><span class="pre">logtalk</span></code><a class="headerlink" href="#the-built-in-object-logtalk" title="Link to this heading"></a></h3>
<p>The built-in <a class="reference external" href="../../apis/logtalk_0.html#logtalk-0" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">logtalk</span></a> object provides
<a class="reference internal" href="printing.html#printing-messages"><span class="std std-ref">message printing</span></a> predicates,
<a class="reference internal" href="printing.html#printing-questions"><span class="std std-ref">question asking</span></a> predicates,
<a class="reference internal" href="debugging.html#debugging-events"><span class="std std-ref">debug and trace event</span></a> predicates, predicates for
accessing the internal database of loaded files and their properties, and
also a set of low-level utility predicates normally used when defining hook
objects. Consult its API documentation for details.</p>
</section>
</section>
<section id="multi-threading-applications">
<h2>Multi-threading applications<a class="headerlink" href="#multi-threading-applications" title="Link to this heading"></a></h2>
<p>When writing multi-threading applications, user-defined predicates calling
built-in predicates such as <code class="docutils literal notranslate"><span class="pre">create_object/4</span></code> and <code class="docutils literal notranslate"><span class="pre">abolish_object/1</span></code> may
need to be declared synchronized in order to avoid race conditions.</p>
</section>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="messages.html" class="btn btn-neutral float-left" title="Messages" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="protocols.html" class="btn btn-neutral float-right" title="Protocols" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 1998-2025, Paulo Moura.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>